| Server IP : 121.121.20.254 / Your IP : 216.73.216.202 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Python315/Doc/html/library/ |
Upload File : |
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="pstats — Statistics for profilers" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/pstats.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Source code: Lib/pstats.py The pstats module provides tools for reading, manipulating, and displaying profiling statistics generated by Python’s profilers. It reads output from both profiling.traci..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Source code: Lib/pstats.py The pstats module provides tools for reading, manipulating, and displaying profiling statistics generated by Python’s profilers. It reads output from both profiling.traci..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>pstats — Statistics for profilers — Python 3.15.0rc1 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=791e38b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0rc1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="timeit — Measure execution time of small code snippets" href="timeit.html" />
<link rel="prev" title="profiling.sampling — Statistical profiler" href="profiling.sampling.html" />
<link rel="canonical" href="https://docs.python.org/3/library/pstats.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a><ul>
<li><a class="reference internal" href="#reading-and-displaying-profile-data">Reading and displaying profile data</a><ul>
<li><a class="reference internal" href="#working-with-statistics">Working with statistics</a></li>
<li><a class="reference internal" href="#filtering-output">Filtering output</a></li>
<li><a class="reference internal" href="#analyzing-call-relationships">Analyzing call relationships</a></li>
<li><a class="reference internal" href="#combining-multiple-profiles">Combining multiple profiles</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-stats-class">The <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> class</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="profiling.sampling.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code> — Statistical profiler</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="timeit.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">timeit</span></code> — Measure execution time of small code snippets</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/pstats.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/pstats.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="timeit.html" title="timeit — Measure execution time of small code snippets"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="profiling.sampling.html" title="profiling.sampling — Statistical profiler"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="debug.html" accesskey="U">Debugging and profiling</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-pstats">
<span id="pstats-statistics-for-profilers"></span><span id="pstats-module"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers<a class="headerlink" href="#module-pstats" title="Link to this heading">¶</a></h1>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/pstats.py">Lib/pstats.py</a></p>
<hr class="docutils" />
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> module provides tools for reading, manipulating, and
displaying profiling statistics generated by Python’s profilers. It reads
output from both <a class="reference internal" href="profiling.tracing.html#module-profiling.tracing" title="profiling.tracing: Deterministic tracing profiler for Python programs."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code></a> (deterministic profiler) and
<a class="reference internal" href="profiling.sampling.html#module-profiling.sampling" title="profiling.sampling: Statistical sampling profiler for Python processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code></a> (statistical profiler).</p>
<section id="reading-and-displaying-profile-data">
<h2>Reading and displaying profile data<a class="headerlink" href="#reading-and-displaying-profile-data" title="Link to this heading">¶</a></h2>
<p>The <a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> class is the primary interface for working with profile
data. It can read statistics from files or directly from a
<a class="reference internal" href="profiling.tracing.html#profiling.tracing.Profile" title="profiling.tracing.Profile"><code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code></a> object.</p>
<p>Load statistics from a file and print a basic report:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pstats</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'profile_output.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> object provides methods for sorting and filtering the
data before printing. For example, to see the ten functions with the highest
cumulative time:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pstats</span><span class="w"> </span><span class="kn">import</span> <span class="n">SortKey</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'profile_output.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<section id="working-with-statistics">
<h3>Working with statistics<a class="headerlink" href="#working-with-statistics" title="Link to this heading">¶</a></h3>
<p>The <a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> class supports method chaining, making it convenient to
perform multiple operations:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'restats'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">strip_dirs</span><span class="p">()</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#pstats.Stats.strip_dirs" title="pstats.Stats.strip_dirs"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strip_dirs()</span></code></a> method removes directory paths from filenames,
making the output more compact. The <a class="reference internal" href="#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sort_stats()</span></code></a> method accepts
various keys to control the sort order.</p>
<p>Different sort keys highlight different aspects of performance:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pstats</span><span class="w"> </span><span class="kn">import</span> <span class="n">SortKey</span>
<span class="c1"># Functions that consume the most cumulative time</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># Functions that consume the most time in their own code</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">TIME</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># Functions sorted by name</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">NAME</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="filtering-output">
<h3>Filtering output<a class="headerlink" href="#filtering-output" title="Link to this heading">¶</a></h3>
<p>The <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a> method accepts restrictions that filter
which functions are displayed. Restrictions can be integers (limiting the
count), floats between 0 and 1 (selecting a percentage), or strings (matching
function names via regular expression).</p>
<p>Print only the top 10%:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mf">.1</span><span class="p">)</span>
</pre></div>
</div>
<p>Print only functions whose names contain “init”:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="s1">'init'</span><span class="p">)</span>
</pre></div>
</div>
<p>Combine restrictions (they apply sequentially):</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Top 10%, then only those containing "init"</span>
<span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mf">.1</span><span class="p">,</span> <span class="s1">'init'</span><span class="p">)</span>
<span class="c1"># Functions in files matching "foo:", limited to top 50%</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">FILENAME</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="s1">'foo:'</span><span class="p">,</span> <span class="mf">.5</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="analyzing-call-relationships">
<h3>Analyzing call relationships<a class="headerlink" href="#analyzing-call-relationships" title="Link to this heading">¶</a></h3>
<p>The <a class="reference internal" href="#pstats.Stats.print_callers" title="pstats.Stats.print_callers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_callers()</span></code></a> method shows which functions called each
displayed function:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_callers</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#pstats.Stats.print_callees" title="pstats.Stats.print_callees"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_callees()</span></code></a> method shows the opposite relationship,
listing which functions each displayed function called:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_callees</span><span class="p">()</span>
</pre></div>
</div>
<p>Both methods accept the same restriction arguments as <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a>.</p>
</section>
<section id="combining-multiple-profiles">
<h3>Combining multiple profiles<a class="headerlink" href="#combining-multiple-profiles" title="Link to this heading">¶</a></h3>
<p>Statistics from multiple profiling runs can be combined into a single
<a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> object:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Load multiple files at once</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'run1.prof'</span><span class="p">,</span> <span class="s1">'run2.prof'</span><span class="p">,</span> <span class="s1">'run3.prof'</span><span class="p">)</span>
<span class="c1"># Or add files incrementally</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'run1.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">'run2.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">'run3.prof'</span><span class="p">)</span>
</pre></div>
</div>
<p>When files are combined, statistics for identical functions (same file, line,
and name) are accumulated, giving an aggregate view across all profiling runs.</p>
</section>
</section>
<section id="the-stats-class">
<h2>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> class<a class="headerlink" href="#the-stats-class" title="Link to this heading">¶</a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="pstats.Stats">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pstats.</span></span><span class="sig-name descname"><span class="pre">Stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">filenames_or_profile</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stream</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">sys.stdout</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats" title="Link to this definition">¶</a></dt>
<dd><p>Create a statistics object from profile data.</p>
<p>The arguments can be filenames (strings or path-like objects) or
<a class="reference internal" href="profiling.tracing.html#profiling.tracing.Profile" title="profiling.tracing.Profile"><code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code></a> objects. If multiple sources are
provided, their statistics are combined.</p>
<p>The <em>stream</em> argument specifies where output from <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a> and
related methods is written. It defaults to <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a>.</p>
<p>The profile data format is specific to the Python version that created it.
There is no compatibility guarantee between Python versions or between
different profilers.</p>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.strip_dirs">
<span class="sig-name descname"><span class="pre">strip_dirs</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.strip_dirs" title="Link to this definition">¶</a></dt>
<dd><p>Remove leading path information from all filenames.</p>
<p>This method modifies the object in place and returns it for method
chaining. After stripping, the statistics are considered to be in
random order.</p>
<p>If stripping causes two functions to become indistinguishable (same
filename, line number, and function name), their statistics are
combined into a single entry.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.add">
<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">filenames</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.add" title="Link to this definition">¶</a></dt>
<dd><p>Add profiling data from additional files.</p>
<p>The files must have been created by the same profiler type. Statistics
for identical functions are accumulated.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.dump_stats">
<span class="sig-name descname"><span class="pre">dump_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.dump_stats" title="Link to this definition">¶</a></dt>
<dd><p>Save the current statistics to a file.</p>
<p>The file is created if it does not exist and overwritten if it does.
The saved data can be loaded by creating a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> object.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.sort_stats">
<span class="sig-name descname"><span class="pre">sort_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">keys</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.sort_stats" title="Link to this definition">¶</a></dt>
<dd><p>Sort the statistics according to the specified criteria.</p>
<p>Each key can be a string or a <a class="reference internal" href="#pstats.SortKey" title="pstats.SortKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">SortKey</span></code></a> enum member. When
multiple keys are provided, later keys break ties in earlier keys.</p>
<p>Using <a class="reference internal" href="#pstats.SortKey" title="pstats.SortKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">SortKey</span></code></a> enum members is preferred over strings as it
provides better error checking:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pstats</span><span class="w"> </span><span class="kn">import</span> <span class="n">SortKey</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span>
</pre></div>
</div>
<p>Valid sort keys:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>String</p></th>
<th class="head"><p>Enum</p></th>
<th class="head"><p>Meaning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'calls'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.CALLS</span></code></p></td>
<td><p>call count</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'cumulative'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.CUMULATIVE</span></code></p></td>
<td><p>cumulative time</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'cumtime'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>cumulative time</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'file'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>file name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'filename'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.FILENAME</span></code></p></td>
<td><p>file name</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'module'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>file name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'ncalls'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>call count</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'pcalls'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.PCALLS</span></code></p></td>
<td><p>primitive call count</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'line'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.LINE</span></code></p></td>
<td><p>line number</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'name'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.NAME</span></code></p></td>
<td><p>function name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'nfl'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.NFL</span></code></p></td>
<td><p>name/file/line</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'stdname'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.STDNAME</span></code></p></td>
<td><p>standard name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'time'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.TIME</span></code></p></td>
<td><p>internal time</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'tottime'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>internal time</p></td>
</tr>
</tbody>
</table>
<p>All sorts on statistics are in descending order (most time consuming
first), while name, file, and line number sorts are ascending
(alphabetical).</p>
<p>The difference between <code class="docutils literal notranslate"><span class="pre">SortKey.NFL</span></code> and <code class="docutils literal notranslate"><span class="pre">SortKey.STDNAME</span></code> is that
NFL sorts line numbers numerically while STDNAME sorts them as strings.
<code class="docutils literal notranslate"><span class="pre">sort_stats(SortKey.NFL)</span></code> is equivalent to
<code class="docutils literal notranslate"><span class="pre">sort_stats(SortKey.NAME,</span> <span class="pre">SortKey.FILENAME,</span> <span class="pre">SortKey.LINE)</span></code>.</p>
<p>For backward compatibility, the numeric arguments <code class="docutils literal notranslate"><span class="pre">-1</span></code>, <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code>,
and <code class="docutils literal notranslate"><span class="pre">2</span></code> are also accepted, meaning <code class="docutils literal notranslate"><span class="pre">'stdname'</span></code>, <code class="docutils literal notranslate"><span class="pre">'calls'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'time'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'cumulative'</span></code> respectively.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7: </span>The <a class="reference internal" href="#pstats.SortKey" title="pstats.SortKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">SortKey</span></code></a> enum.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.reverse_order">
<span class="sig-name descname"><span class="pre">reverse_order</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.reverse_order" title="Link to this definition">¶</a></dt>
<dd><p>Reverse the current sort order.</p>
<p>By default, the sort direction is chosen appropriately for the sort key
(descending for time-based keys, ascending for name-based keys). This
method inverts that choice.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.print_stats">
<span class="sig-name descname"><span class="pre">print_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">restrictions</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.print_stats" title="Link to this definition">¶</a></dt>
<dd><p>Print a report of the profiling statistics.</p>
<p>The output includes a header line summarizing the data, followed by a
table of function statistics sorted according to the last
<a class="reference internal" href="#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sort_stats()</span></code></a> call.</p>
<p>Restrictions filter the output. Each restriction is either:</p>
<ul class="simple">
<li><p>An integer: limits output to that many entries</p></li>
<li><p>A float between 0.0 and 1.0: selects that fraction of entries</p></li>
<li><p>A string: matches function names via regular expression</p></li>
</ul>
<p>Restrictions are applied sequentially. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">print_stats</span><span class="p">(</span><span class="mf">.1</span><span class="p">,</span> <span class="s1">'foo:'</span><span class="p">)</span>
</pre></div>
</div>
<p>First limits to the top 10%, then filters to functions matching ‘foo:’.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.print_callers">
<span class="sig-name descname"><span class="pre">print_callers</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">restrictions</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.print_callers" title="Link to this definition">¶</a></dt>
<dd><p>Print the callers of each function in the statistics.</p>
<p>For each function in the filtered results, shows which functions called
it and how often.</p>
<p>With <a class="reference internal" href="profiling.tracing.html#module-profiling.tracing" title="profiling.tracing: Deterministic tracing profiler for Python programs."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code></a> (or <code class="docutils literal notranslate"><span class="pre">cProfile</span></code>), each caller line
shows three numbers: the number of calls from that caller, and the
total and cumulative times for those specific calls.</p>
<p>Accepts the same restriction arguments as <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.print_callees">
<span class="sig-name descname"><span class="pre">print_callees</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">restrictions</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.print_callees" title="Link to this definition">¶</a></dt>
<dd><p>Print the functions called by each function in the statistics.</p>
<p>This is the inverse of <a class="reference internal" href="#pstats.Stats.print_callers" title="pstats.Stats.print_callers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_callers()</span></code></a>, showing which functions
each listed function called.</p>
<p>Accepts the same restriction arguments as <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.get_stats_profile">
<span class="sig-name descname"><span class="pre">get_stats_profile</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.get_stats_profile" title="Link to this definition">¶</a></dt>
<dd><p>Return a <code class="docutils literal notranslate"><span class="pre">StatsProfile</span></code> object containing the statistics.</p>
<p>The returned object provides programmatic access to the profile data,
with function names mapped to <code class="docutils literal notranslate"><span class="pre">FunctionProfile</span></code> objects
containing timing and call count information.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="pstats.SortKey">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pstats.</span></span><span class="sig-name descname"><span class="pre">SortKey</span></span><a class="headerlink" href="#pstats.SortKey" title="Link to this definition">¶</a></dt>
<dd><p>An enumeration of valid sort keys for <a class="reference internal" href="#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Stats.sort_stats()</span></code></a>.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.CALLS">
<span class="sig-name descname"><span class="pre">CALLS</span></span><a class="headerlink" href="#pstats.SortKey.CALLS" title="Link to this definition">¶</a></dt>
<dd><p>Sort by call count.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.CUMULATIVE">
<span class="sig-name descname"><span class="pre">CUMULATIVE</span></span><a class="headerlink" href="#pstats.SortKey.CUMULATIVE" title="Link to this definition">¶</a></dt>
<dd><p>Sort by cumulative time.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.FILENAME">
<span class="sig-name descname"><span class="pre">FILENAME</span></span><a class="headerlink" href="#pstats.SortKey.FILENAME" title="Link to this definition">¶</a></dt>
<dd><p>Sort by file name.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.LINE">
<span class="sig-name descname"><span class="pre">LINE</span></span><a class="headerlink" href="#pstats.SortKey.LINE" title="Link to this definition">¶</a></dt>
<dd><p>Sort by line number.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.NAME">
<span class="sig-name descname"><span class="pre">NAME</span></span><a class="headerlink" href="#pstats.SortKey.NAME" title="Link to this definition">¶</a></dt>
<dd><p>Sort by function name.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.NFL">
<span class="sig-name descname"><span class="pre">NFL</span></span><a class="headerlink" href="#pstats.SortKey.NFL" title="Link to this definition">¶</a></dt>
<dd><p>Sort by name, then file, then line number (numeric line sort).</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.PCALLS">
<span class="sig-name descname"><span class="pre">PCALLS</span></span><a class="headerlink" href="#pstats.SortKey.PCALLS" title="Link to this definition">¶</a></dt>
<dd><p>Sort by primitive (non-recursive) call count.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.STDNAME">
<span class="sig-name descname"><span class="pre">STDNAME</span></span><a class="headerlink" href="#pstats.SortKey.STDNAME" title="Link to this definition">¶</a></dt>
<dd><p>Sort by standard name (string-based line sort).</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.TIME">
<span class="sig-name descname"><span class="pre">TIME</span></span><a class="headerlink" href="#pstats.SortKey.TIME" title="Link to this definition">¶</a></dt>
<dd><p>Sort by internal time (time in function excluding subcalls).</p>
</dd></dl>
</dd></dl>
</section>
<section id="command-line-interface">
<span id="pstats-cli"></span><h2>Command-line interface<a class="headerlink" href="#command-line-interface" title="Link to this heading">¶</a></h2>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> module can be invoked as a script to interactively browse
profile data:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pstats</span> <span class="n">profile_output</span><span class="o">.</span><span class="n">prof</span>
</pre></div>
</div>
<p>This opens a line-oriented interface (built on <a class="reference internal" href="cmd.html#module-cmd" title="cmd: Build line-oriented command interpreters."><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmd</span></code></a>) for examining the
statistics. Type <code class="docutils literal notranslate"><span class="pre">help</span></code> at the prompt for available commands.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="profiling.html#module-profiling" title="profiling: Python profiling tools for performance analysis."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code></a></dt><dd><p>Overview of Python profiling tools.</p>
</dd>
<dt><a class="reference internal" href="profiling.tracing.html#module-profiling.tracing" title="profiling.tracing: Deterministic tracing profiler for Python programs."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code></a></dt><dd><p>Deterministic tracing profiler.</p>
</dd>
<dt><a class="reference internal" href="profiling.sampling.html#module-profiling.sampling" title="profiling.sampling: Statistical sampling profiler for Python processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code></a></dt><dd><p>Statistical sampling profiler.</p>
</dd>
</dl>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a><ul>
<li><a class="reference internal" href="#reading-and-displaying-profile-data">Reading and displaying profile data</a><ul>
<li><a class="reference internal" href="#working-with-statistics">Working with statistics</a></li>
<li><a class="reference internal" href="#filtering-output">Filtering output</a></li>
<li><a class="reference internal" href="#analyzing-call-relationships">Analyzing call relationships</a></li>
<li><a class="reference internal" href="#combining-multiple-profiles">Combining multiple profiles</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-stats-class">The <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> class</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="profiling.sampling.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code> — Statistical profiler</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="timeit.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">timeit</span></code> — Measure execution time of small code snippets</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/pstats.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/pstats.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="timeit.html" title="timeit — Measure execution time of small code snippets"
>next</a> |</li>
<li class="right" >
<a href="profiling.sampling.html" title="profiling.sampling — Statistical profiler"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="debug.html" >Debugging and profiling</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Aug 04, 2026 (11:13 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>